The GrADS scripting language, used via the GrADS run command, provides a similar capability to the exec command, except that a script may have variables, flow control, and access GrADS command output. Scripts may be written to perform a variety of functions, such as allowing a user to point and click on the screen to select something, to animate any desired quantities, to annotate plots with information obtained from GrADS query commands.
The command to execute a script is the run command:
run file-name options
This command runs the script contained in the named file. See Appendix B for documentation of the scripting language.
Some GrADS commands that complement the scripting langauge are:
query <option>
Issue the query command with no options to see what options are available.
coordinate transformations
- query commands have been provided to do general coordinate transformations:
query transform value1 value2
where transform is one of:
xy2w - XY coords to world coords
xy2gr - XY coords to grid coords
w2xy - world coords to XY coords
w2gr - world coords to grid coords
gr2w - grid coords to world coords
gr2xy - grid coords to XY coords
These queries are valid ONLY AFTER something has been displayed. The tranformations apply ONLY to the most recent item that has been displayed.
XY coords are inches on the page (ie, screen) where the page is 11x8.5 inches or 8.5x11 inches, depending on how GrADS was started.
World coords are lat, lon, lev, time or val, depending on what the dimension environment is when the grid was displayed. Note that time is displayed (and must be specified) in GrADS absolute date/time format. val is the value coordinate for a 1-D plot (line graph).
Grid coordinates are the coordinates with respect to the grid being displayed. For station data sets, grid and world coordinates are equivalent except for the time dimension. Note that if you display a grid from a 'wrapped' data set, the grid numbers may be out of range of the actual file grid numbers. (A 'wrapped' data set is a data set that covers the earth in the longitude direction. Wrapping takes place automatically). The conversions are done consistently, but you may want to be sure you can handle the wrapping case if your data set is global.
Example:
You have displayed a Hovmoller diagram:
query xy2w 5.0 4.5
The response might be:
Lon = -95 Time = 00z5nov1992
set gxout findstn
This graphics output type expects three arguments via a display command. The first argument is a station data argument. The 2nd and 3rd arguments are the X and Y position on the screen of the desired search coordinates. GrADS will search for the nearest station to the specified X and Y position, and print the stid, lon, and lat of the station found. This should only be used when X and Y are the varying dimensions and AFTER a regular display command (that results in graphics output) is entered.
This command is primarily intended for use with a script. Note that this command is provided as an interim facility for doing this operation; a more complete facility will be provided for doing a variety of filtering and search operations. Thus, you should isolate the use of the command in your scripts in case it is necessary to change it later.
set dbuff on|off
Sets double buffer mode on or off. This allows animation to be controlled from a script. The clear command also sets double buffer mode off.
swap
Swaps buffers, when double buffer mode is on. If double buffer mode is off, this command has no effect.
The usual usage of these command would be:
set dbuff on
loop --->
display something
swap
<--- endloop
set dbuff off
Scripting variables are usually local to the functions they are contained in. Global scripting variables are also available. They are specified via the variable name. Any variable name starting with an underscore (_) will be assumed to be a global variable, and will keep its value throughout an entire script file. Note that global variables cannot be used in function headers:
function dostuff(_var)
would be invalid.
You may have a simple script automatically executed before every display command:
set imprun script-name
This script would typically be used to set an option that by default gets reset after each display command:
'set grads off'
You can issue any GrADS command from this script, but the interactions are not always clear. For example, if you issued a display command from this script, you could easily enter an infinite recursion loop.
The argument to the script is the expression from the display command.
XY coords are inches on the page (ie, screen) where the page is 11x8.5 inches or 8.5x11 inches, depending on how GrADS was started.
World coords are lat, lon, lev, time or val, depending on what the dimension environment is when the grid was displayed. Note that time is displayed (and must be specified) in GrADS absolute date/time format. val is the value coordinate for a 1-D plot (line graph).
Grid coordinates are the coordinates with respect to the grid being displayed. For station data sets, grid and world coordinates are equivalent except for the time dimension. Note that if you display a grid from a 'wrapped' data set, the grid numbers may be out of range of the actual file grid numbers. (A 'wrapped' data set is a data set that covers the earth in the longitude direction. Wrapping takes place automatically). The conversions are done consistently, but you may want to be sure you can handle the wrapping case if your data set is global.
Example:
You have displayed a Hovmoller diagram:
query xy2w 5.0 4.5
The response might be:
Lon = -95 Time = 00z5nov1992
set gxout findstn
This graphics output type expects three arguments via a display command. The first argument is a station data argument. The 2nd and 3rd arguments are the X and Y position on the screen of the desired search coordinates. GrADS will search for the nearest station to the specified X and Y position, and print the stid, lon, and lat of the station found. This should only be used when X and Y are the varying dimensions and AFTER a regular display command (that results in graphics output) is entered.
This command is primarily intended for use with a script. Note that this command is provided as an interim facility for doing this operation; a more complete facility will be provided for doing a variety of filtering and search operations. Thus, you should isolate the use of the command in your scripts in case it is necessary to change it later.
set dbuff on|off
Sets double buffer mode on or off. This allows animation to be controlled from a script. The clear command also sets double buffer mode off.
swap
Swaps buffers, when double buffer mode is on. If double buffer mode is off, this command has no effect.
The usual usage of these command would be:
set dbuff on
loop --->
display something
swap
<--- endloop
set dbuff off
Scripting variables are usually local to the functions they are contained in. Global scripting variables are also available. They are specified via the variable name. Any variable name starting with an underscore (_) will be assumed to be a global variable, and will keep its value throughout an entire script file. Note that global variables cannot be used in function headers:
function dostuff(_var)
would be invalid (not really true -- mf).
You may have a simple script automatically executed before every display command:
set imprun script-name
This script would typically be used to set an option that by default gets reset after each display command:
'set grads off'
You can issue any GrADS command from this script, but the interactions are not always clear. For example, if you issued a display command from this script, you could easily enter an infinite recursion loop.
The argument to the script is the expression from the display command.